home *** CD-ROM | disk | FTP | other *** search
-
-
-
- Tcl_CreateTrace(3) Tcl Library Procedures
-
-
-
- _________________________________________________________________
-
- NAME
- Tcl_CreateTrace, Tcl_DeleteTrace - arrange for command exe-
- cution to be traced
-
- SYNOPSIS
- #include <tcl.h>
-
- Tcl_Trace
- Tcl_CreateTrace(_i_n_t_e_r_p, _l_e_v_e_l, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
-
- Tcl_DeleteTrace(_i_n_t_e_r_p, _t_r_a_c_e)
-
- ARGUMENTS
- Tcl_Interp *_i_n_t_e_r_p (in) Interpreter
- containing
- command to be
- traced or
- untraced.
-
- int _l_e_v_e_l (in) Only commands
- at or below
- this nesting
- level will be
- traced. 1
- means top-
- level commands
- only, 2 means
- top-level com-
- mands or those
- that are
- invoked as
- immediate
- consequences
- of executing
- top-level com-
- mands (pro-
- cedure bodies,
- bracketed com-
- mands, etc.)
- and so on.
-
- Tcl_CmdTraceProc *_p_r_o_c (in) Procedure to
- call for each
- command that's
- executed. See
- below for
- details on the
- calling
- sequence.
-
-
-
-
- Tcl 1
-
-
-
-
-
-
- Tcl_CreateTrace(3) Tcl Library Procedures
-
-
-
- ClientData _c_l_i_e_n_t_D_a_t_a (in) Arbitrary
- one-word value
- to pass to
- _p_r_o_c.
-
- Tcl_Trace _t_r_a_c_e (in) Token for
- trace to be
- removed
- (return value
- from previous
- call to
- Tcl_CreateTrace).
- _________________________________________________________________
-
-
- DESCRIPTION
- Tcl_CreateTrace arranges for command tracing. From now on,
- _p_r_o_c will be invoked before Tcl calls command procedures to
- process commands in _i_n_t_e_r_p. The return value from
- Tcl_CreateTrace is a token for the trace, which may be
- passed to Tcl_DeleteTrace to remove the trace. There may be
- many traces in effect simultaneously for the same command
- interpreter.
-
- _P_r_o_c should have arguments and result that match the type
- Tcl_CmdTraceProc:
-
- typedef void Tcl_CmdTraceProc(
- ClientData _c_l_i_e_n_t_D_a_t_a,
- Tcl_Interp *_i_n_t_e_r_p,
- int _l_e_v_e_l,
- char *_c_o_m_m_a_n_d,
- Tcl_CmdProc *_c_m_d_P_r_o_c,
- ClientData _c_m_d_C_l_i_e_n_t_D_a_t_a,
- int _a_r_g_c,
- char *_a_r_g_v[]));
-
- The _c_l_i_e_n_t_D_a_t_a and _i_n_t_e_r_p parameters are copies of the
- corresponding arguments given to Tcl_CreateTrace. _C_l_i_e_n_t_-
- _D_a_t_a typically points to an application-specific data struc-
- ture that describes what to do when _p_r_o_c is invoked. _L_e_v_e_l
- gives the nesting level of the command (1 for top-level com-
- mands passed to Tcl_Eval by the application, 2 for the
- next-level commands passed to Tcl_Eval as part of parsing or
- interpreting level-1 commands, and so on). _C_o_m_m_a_n_d points
- to a string containing the text of the command, before any
- argument substitution. _C_m_d_P_r_o_c contains the address of the
- command procedure that will be called to process the command
- (i.e. the _p_r_o_c argument of some previous call to
- Tcl_CreateCommand) and _c_m_d_C_l_i_e_n_t_D_a_t_a contains the associated
- client data for _c_m_d_P_r_o_c (the _c_l_i_e_n_t_D_a_t_a value passed to
- Tcl_CreateCommand). _A_r_g_c and _a_r_g_v give the final argument
-
-
-
- Tcl 2
-
-
-
-
-
-
- Tcl_CreateTrace(3) Tcl Library Procedures
-
-
-
- information that will be passed to _c_m_d_P_r_o_c, after command,
- variable, and backslash substitution. _P_r_o_c must not modify
- the _c_o_m_m_a_n_d or _a_r_g_v strings.
-
- Tracing will only occur for commands at nesting level less
- than or equal to the _l_e_v_e_l parameter (i.e. the _l_e_v_e_l parame-
- ter to _p_r_o_c will always be less than or equal to the _l_e_v_e_l
- parameter to Tcl_CreateTrace).
-
- Calls to _p_r_o_c will be made by the Tcl parser immediately
- before it calls the command procedure for the command
- (_c_m_d_P_r_o_c). This occurs after argument parsing and substitu-
- tion, so tracing for substituted commands occurs before
- tracing of the commands containing the substitutions. If
- there is a syntax error in a command, or if there is no com-
- mand procedure associated with a command name, then no trac-
- ing will occur for that command. If a string passed to
- Tcl_Eval contains multiple commands (bracketed, or on dif-
- ferent lines) then multiple calls to _p_r_o_c will occur, one
- for each command. The _c_o_m_m_a_n_d string for each of these
- trace calls will reflect only a single command, not the
- entire string passed to Tcl_Eval.
-
- Tcl_DeleteTrace removes a trace, so that no future calls
- will be made to the procedure associated with the trace.
- After Tcl_DeleteTrace returns, the caller should never again
- use the _t_r_a_c_e token.
-
-
- KEYWORDS
- command, create, delete, interpreter, trace
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Tcl 3
-
-
-
-
